Inside Macintosh: AppleScript Scripting Additions Guide /

Chapter 2 - Scripting Addition Commands / Command Definitions

/

Display Dialog

The Display Dialog command displays a dialog box like the one shown in Figure 2-4. The dialog box contains a string and one or more buttons, such as Yes and No, or OK and Cancel. The dialog box may also contain an icon and a field in which the user can enter text.

The Display Dialog command is the only command provided by the Display Dialog scripting addition.

Figure 2-4 A Display Dialog dialog box

SYNTAX

display dialog questionString                         ¬
   [ default answer answerString ]                    ÿ   [ buttons buttonList]                              ÿ   [ default button buttonNumberOrName ]              ÿ   [ with icon iconNumberOrName ]

PARAMETERS

questionString

The string displayed in the dialog box. The string can be up to 255 characters long.
Class: String

answerString

The default string provided in a text field that the user can edit. The string can be up to 255 characters long. If you omit the default answer parameter, the dialog box does not include an editable text field. If you specify an empty string (""), the dialog box has an editable text field with no default answer.
Class: String

buttonList

The list of buttons that appear in the dialog box. Each item in the list is a string containing the text that appears in the button. The first string in the list is the string for the leftmost button, the second string is the string for the next button, and so on. You can specify up to three buttons. If you omit the buttons parameter, the dialog contains two buttons: Cancel and OK.
Class: List of strings

buttonNumberOrName

The default button. You can specify the default button with a string (the string provided for the button in buttonList) or with an integer (which specifies the position of the button in the buttonList list; 1 specifies the first button from the left, 2 specifies the second button from the left, and so on).
Class: String or integer

iconNumberOrName

The icon to be included in the dialog box. This can be either a string that specifies the name of an 'ICON' resource or an integer that specifies the number of the resource (see "Notes").
Class: String

RESULT

A record of object class Reply (defined by the Display Dialog scripting addition) that contains the following properties:

button returned


The text of the button the user pressed to close the dialog box.
Class: String

text returned


The text from the editable text field in the dialog box. If the dialog does not include an editable text field, no string is returned. If there is no text in the field, the value is the empty string ("").
Class: String

EXAMPLE

The following example uses the Display Dialog command to prompt the user for a password.

set prompt to "Please enter password:"repeat with i from 1 to 4
   set dialogResult to display dialog prompt ÿ      buttons {"I give up", "OK"} default button 2 ÿ      default answer  "Joe User" with icon 1
   if button returned of dialogResult = "I give up" then
      error number -128 --user canceled
   else
      if text returned of dialogResult = "magic" then
         exit
      else
         if i < 3 then
            set prompt to "Password was incorrect.  Try " ÿ               & i + 1
         else
            set prompt to ÿ               "Password was incorrect.  Last Chance!"         end if
      end if
   end if
end repeat

NOTES

The size of the dialog box is determined by the lengths of the question and answer strings.

As an alternative to the Cancel button, the user can press Command-period or the Esc key to cancel a dialog box displayed by the Display Dialog command.

A dialog box can include an icon stored in the script file, the current application (as specified by a Tell statement), or the System file. If there is an icon with the specified name or number in the script file, it is used; otherwise, AppleScript checks the current application; finally, if the specified icon is not found in either the script file or the current application, AppleScript checks the System file. If you are using a system that provides Color QuickDraw and the specified icon is available as a color icon, the color icon is displayed. To add icons to a script or application file, use a resource tool such as ResEdit.

The System file provides three standard icons to warn the user about problems. These icons, illustrated in Figure 2-5, have the following meanings:

• Stop (icon number 0). Use this icon to call attention to a serious problem that requires the user to choose from alternative courses of action.
• Note (icon number 1). Use this icon to provide information about a situation that has no drastic effects. The user usually responds by pressing the
  OK button.
• Caution (icon number 2). Use this icon to call attention to an operation that may have undesirable results if allowed to continue. You normally give the user a choice to continue or not.

Figure 2-5 Alert icons

To use these icons, refer to them by number. For example, this script displays the caution icon, the string, and the default OK and Cancel buttons.

display dialog "Your fuselage is melting. Eject now?" ÿ   with icon 2

ERRORS

Error number	Error message
-108	Out of memory.
-128	User canceled.
-192	A resource wasn't found.
-1712	AppleEvent timed out.